'\" te
.\"  Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH TRAN_START 9E "April 9, 2016"
.SH NAME
tran_start \- request to transport a SCSI command
.SH SYNOPSIS
.nf
#include <sys/scsi/scsi.h>



\fBint prefix\fR\fBtran_start\fR(\fBstruct scsi_address *\fR\fIap\fR,
     \fBstruct scsi_pkt *\fR\fIpkt\fR);
.fi

.SH INTERFACE LEVEL
illumos architecture specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fIpkt\fR \fR
.ad
.RS 8n
Pointer to the  \fBscsi_pkt\fR(9S) structure that is about to be transferred.
.RE

.sp
.ne 2
.na
\fB\fIap\fR \fR
.ad
.RS 8n
Pointer to a \fBscsi_address\fR(9S) structure.
.RE

.SH DESCRIPTION
The  \fBtran_start()\fR vector in the  \fBscsi_hba_tran\fR(9S) structure must
be initialized during the \fBHBA \fRdriver's \fBattach\fR(9E) to point to an
\fBHBA \fRentry point to be called when a target driver calls
\fBscsi_transport\fR(9F).
.sp
.LP
\fBtran_start()\fR must perform the necessary operations on the \fBHBA
\fRhardware to transport the \fBSCSI \fRcommand in the  \fIpkt\fR structure to
the target/logical unit device specified in the  \fIap\fR structure.
.sp
.LP
If the flag  \fBFLAG_NOINTR\fR is set in  \fBpkt_flags\fR in  \fIpkt\fR,
\fBtran_start()\fR should not return until the command has been completed. The
command completion callback \fBpkt_comp\fR in  \fIpkt\fR must not be called for
commands with  \fBFLAG_NOINTR\fR set, since the return is made directly to the
function invoking \fBscsi_transport\fR(9F).
.sp
.LP
When the flag  \fBFLAG_NOINTR\fR is not set,  \fBtran_start()\fR must queue the
command for execution on the hardware and return immediately.  The member
\fBpkt_comp\fR in  \fIpkt\fR indicates a callback routine to be called upon
command completion.
.sp
.LP
Refer to  \fBscsi_pkt\fR(9S) for other bits in  \fBpkt_flags\fR for which the
\fBHBA \fRdriver may need to adjust how the command is managed.
.sp
.LP
If the  \fBauto_rqsense\fR capability has been set, and the status length
allocated in  \fBtran_init_pkt\fR(9E) is greater than or equal to
\fBsizeof(struct scsi_arq_status)\fR, automatic request sense is enabled for
this  \fIpkt\fR. If the command terminates with a Check Condition, the \fBHBA
\fRdriver must arrange for a Request Sense command to be transported to that
target/logical unit, and the members of the  \fBscsi_arq_status\fR structure
pointed to by  \fBpkt_scbp\fR updated with the results of this Request Sense
command before the \fBHBA \fRdriver completes the command pointed by
\fIpkt\fR.
.sp
.LP
The member  \fBpkt_time\fR in  \fIpkt\fR is the maximum number of seconds in
which the command should complete. Timeout starts when the command is
transmitted on the \fBSCSI\fR bus. A  \fBpkt_time\fR of \fB0\fR means no
timeout should be performed.
.sp
.LP
For a command which has timed out, the \fBHBA \fRdriver must perform some
recovery operation to clear the command in the target, typically an Abort
message, or a Device or Bus Reset.  The \fBpkt_reason\fR member of the timed
out \fIpkt\fR should be set to  \fBCMD_TIMEOUT,\fR and \fBpkt_statistics\fR
\fBOR\fR'ed with  \fBSTAT_TIMEOUT\fR. If the \fBHBA \fRdriver can successfully
recover from the timeout, \fBpkt_statistics\fR must also be  \fBOR\fR'ed with
one of  \fBSTAT_ABORTED\fR, \fBSTAT_BUS_RESET\fR, or  \fBSTAT_DEV_RESET\fR, as
appropriate. This informs the target driver that timeout recovery has already
been successfully accomplished for the timed out command. The  \fBpkt_comp\fR
completion callback, if not  \fINULL\fR, must also be called at the conclusion
of the timeout recovery.
.sp
.LP
If the timeout recovery was accomplished with an Abort Tag message, only the
timed out packet is affected, and the  packet must be returned with
\fBpkt_statistics\fR \fBOR\fR'ed with  \fBSTAT_ABORTED\fR and
\fBSTAT_TIMEOUT\fR.
.sp
.LP
If the timeout recovery was accomplished with an Abort message, all commands
active in that target are affected. All corresponding packets must be returned
with  \fBpkt_reason\fR, \fBCMD_TIMEOUT\fR, and  \fBpkt_statistics\fR
\fBOR\fR'ed with  \fBSTAT_TIMEOUT\fR and  \fBSTAT_ABORTED\fR.
.sp
.LP
If the timeout recovery was accomplished with a Device Reset, all packets
corresponding to commands active in the target must be returned in the
transport layer for this target. Packets corresponding to commands active in
the target must be returned returned with \fBpkt_reason\fR set to
\fBCMD_TIMEOUT\fR, and \fBpkt_statistics\fR \fBOR\fR'ed with
\fBSTAT_DEV_RESET\fR and  \fBSTAT_TIMEOUT\fR. Currently inactive packets queued
for the device should be returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR
and \fBpkt_statistics\fR \fBOR\fR'ed with \fBSTAT_ABORTED\fR.
.sp
.LP
If the timeout recovery was accomplished with a Bus Reset, all  packets
corresponding to commands active in the target must be returned in the
transport layer. Packets corresponding to commands active in the target must be
returned with \fBpkt_reason\fR set to \fBCMD_TIMEOUT\fR and
\fBpkt_statistics\fR \fBOR\fR'ed with \fBSTAT_TIMEOUT\fR and
\fBSTAT_BUS_RESET\fR. All queued packets for other targets on this bus must be
returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR and \fBpkt_statistics\fR
\fBOR'ed\fR with \fBSTAT_ABORTED\fR.
.sp
.LP
Note that after either a Device Reset or a Bus Reset,  the \fBHBA \fRdriver
must enforce a reset delay time of \fB\&'scsi-reset-delay'\fR milliseconds,
during which time no commands should be sent to that device, or any device on
the bus, respectively.
.sp
.LP
\fBtran_start()\fR should initialize the following members in  \fIpkt\fR to
\fB0\fR. Upon command completion, the \fBHBA \fRdriver should ensure that the
values in these members are updated to accurately reflect the states through
which the command transitioned while in the transport layer.
.sp
.ne 2
.na
\fB\fBpkt_resid\fR \fR
.ad
.RS 19n
For commands with data transfer, this member must be updated to indicate the
residual of the data transferred.
.RE

.sp
.ne 2
.na
\fB\fBpkt_reason\fR\fR
.ad
.RS 19n
The reason for the command completion. This field should be set to
\fBCMD_CMPLT\fR at the beginning of \fBtran_start()\fR, then updated if the
command ever transitions to an abnormal termination state. To avoid losing
information, do not set \fBpkt_reason\fR to any other error state unless it
still has its original \fBCMD_CMPLT\fR value.
.RE

.sp
.ne 2
.na
\fB\fBpkt_statistics\fR \fR
.ad
.RS 19n
Bit field of transport-related statistics.
.RE

.sp
.ne 2
.na
\fB\fBpkt_state\fR \fR
.ad
.RS 19n
Bit field with the major states through which a \fBSCSI\fR command can
transition. Note: The members listed above, and \fBpkt_hba_private\fR member,
are the only fields in the \fBscsi_pkt\fR(9S) structure which may be modified
by the transport layer.
.RE

.SH RETURN VALUES
\fBtran_start()\fR must return:
.sp
.ne 2
.na
\fB\fBTRAN_ACCEPT\fR \fR
.ad
.RS 21n
The packet was accepted by the transport layer.
.RE

.sp
.ne 2
.na
\fB\fBTRAN_BUSY\fR \fR
.ad
.RS 21n
The packet could not be accepted because there was already a packet in progress
for this target/logical unit, the \fBHBA \fRqueue was full, or the target
device queue was full.
.RE

.sp
.ne 2
.na
\fB\fBTRAN_BADPKT\fR \fR
.ad
.RS 21n
The \fBDMA \fRcount in the packet exceeded the \fBDMA \fRengine's maximum
\fBDMA \fRsize, or the packet could not be accepted for other reasons.
.RE

.sp
.ne 2
.na
\fB\fBTRAN_FATAL_ERROR\fR \fR
.ad
.RS 21n
A fatal error has occurred in the \fBHBA. \fR
.RE

.SH CONTEXT
The \fBtran_start()\fR function can be called from user or interrupt context.
This requirement comes from \fBscsi_transport()\fR.
.SH SEE ALSO
.BR attach (9E),
.BR tran_init_pkt (9E),
.BR scsi_hba_attach (9F),
.BR scsi_transport (9F),
.BR scsi_address (9S),
.BR scsi_arq_status (9S),
.BR scsi_hba_tran (9S),
.BR scsi_pkt (9S)
.sp
.LP
\fIWriting Device Drivers\fR
